home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 October: Technology Seed / ADC Seed CD - October 1999.toast / FireWire / FireWire_2.0_SDK / Software / FireBug 1.0d7e10 / FireBug Readme 1.0d7e10 < prev   
Encoding:
Text File  |  1999-04-12  |  30.6 KB  |  637 lines  |  [TEXT/ttxt]

  1. FireBug 1.0d7e10 readme
  2.  
  3.  
  4. FireWire is a trademark of Apple Computer, Inc., registered in the United
  5. States and other countries.
  6.  
  7. FireBug is Apple Confidential and may be distributed only by Apple Computer.
  8.  
  9.  
  10. ** SUMMARY **
  11.  
  12. FireBug is a FireWire analyzer/snooper tool.  Firebug examines the packets on a
  13. FireWire bus, and generates various real-time and post-mortem views of the data
  14. that is obtained.  This includes running counts of tCodes, ack types, packet
  15. speeds, and so on, as well as formatted output of user-selected packets, such as
  16. quadlet reads or self-IDs.  A variety of filters can be applied to the bus in
  17. order to select packets of interest for display.
  18.  
  19. Unless certain optional commands (busreset, etc.) are used, FireBug is a passive
  20. entity on the FireWire bus.  FireBug uses the snooping feature in the TI Lynx
  21. (revA and beyond) to receive all packets, regardless of the actual destination
  22. node.  FireBug never sends acknowledgements to any packet.  Other nodes on the
  23. FireWire bus will see FireBug as a dumb repeater, with an active PHY layer only.
  24. Due to hardware limitations, FireBug shows a "Link on" in its self ID, which
  25. may confuse other nodes.  FireBug may be root, but does not act as cycle master,
  26. isochronous resource manager, or bus manager.
  27.  
  28. FireBug is not a supported Apple product.
  29.  
  30. ** CHARTER **
  31.  
  32. FireBug was developed to solve immediate debugging problems, not to be a good
  33. general-purpose FireWire analyzer right from the start.  If you have ideas about
  34. what you'd like to see FireBug do, please let us know.
  35.  
  36. ** INSTALLATION **
  37.  
  38. FireBug is an application, but it directly accesses the hardware in the Lynx card.
  39. Therefore FireBug cannot be used on a Mac running Blaze FireWire software.  All
  40. FireWire software should be removed or disabled before FireBug is used.  [Reboot
  41. after making such changes before running FireBug.]  Because future version of MacOS
  42. should contain built-in FireWire support; it is possible that FireBug will not
  43. be usable on such systems.  The MacOS versions known to work with FireBug are 7.6,
  44. 8.0, and 8.1.
  45.  
  46. FireBug must process tens of thousands of snooped packets each second, so
  47. best performance will be obtained if all unnecessary Mac services are disabled.
  48. For example, disconnect all Ethernet or LocalTalk network cables, disable file
  49. sharing, TCP/IP, Control Strip, screen savers, and any background applications.
  50. Set your monitor to 256 colors or grays.  Remove any CD-ROM discs.  Nearly all
  51. extensions and most control panels can be disabled as well.  In order to get
  52. maximum performance, FireBug deliberately does not participate in cooperative
  53. multi-tasking.  Quit all applications before launching FireBug.
  54.  
  55. FireBug seems to work correctly on these systems: 6360, 7200, 7600, 8500, G3.
  56. FireBug should work correctly on most PCI-based Mac running MacOS 7.6-8.1.
  57. FireBug requires 12100K of RAM, so a Mac with at least 16 megs is suggested.
  58. [Note, 7.6 can run in <4 megs if you remove most extensions, including OT.]
  59. If FireBug cannot locate a PCI-Lynx card in the Name Registry, it will not snoop.
  60. If FireBug finds a pre-revA Lynx, it will explain this, and refuse to snoop.
  61. Note:  FireBug allocates about 9 megs from the system heap.  This means you
  62. need about 12 megs free, total, even though Get Info says only 3 are needed.
  63.  
  64. FireBug can snoop at least 16000 packets/second on a 6360/160 and a 7200/100, and
  65. at least 23200 packets/second on a 7600/200.  However, FireBug cannot format this
  66. many packets per second for display.  On a fast machine such as the PowerMac G3,
  67. FireBug can format 8000 cycle-start packets per second for display and add them
  68. to the scrolling list.  But even on a fast machine, more complicated packets
  69. (such as isochronous data) may overload FireBug.
  70.  
  71. ** ACCURACY **
  72.  
  73. FireBug relies on the PCI-Lynx card for its snooping.  This card is connected
  74. to the CPU by the PCI bus.  Therefore FireBug does not have the ability to do
  75. high-precision timing.  However, FireBug can typically identify event times
  76. with sub-cycle accuracy (less than 125 microseconds).  FireBug should be able
  77. to detect and report any error that causes the loss of a packet.  Unless
  78. FireBug's DMA ring buffer wraps around completely, FireBug can compensate for
  79. falling behind by skipping packets.  A message indicates that this has happened.
  80. By default, FireBug checks the header CRC on all packets, but not the data
  81. CRC.
  82.  
  83. FireBug presently uses a 4096-packet DMA ring, but it will skip packets if it finds
  84. the ring is more than half full, in order to avoid wrapping the ring.  If ring-wrap
  85. is avoided, the exact count of skipped packets is known.  Therefore, any number of
  86. packets can be filtered for display, as long as no more than 2047 packets accumulate
  87. in the DMA ring at once.
  88.  
  89. FireBug counts most values with unsigned 32-bit integers, so it can count at
  90. most 4 billion or so events before the counters overflow.  When receiving several
  91. isochronous streams, this overflow could happen in a day or two.  Don't trust the
  92. counters if you've left FireBug running overnight.  [Snooping output should be
  93. accurate, however.]
  94.  
  95. FireBug snoops up to 2048 bytes per packet, including headers, CRCs, and one or
  96. two quadlets for snoop information.  This means that the largest asynch packet
  97. FireBug can actually snoop is about 1988 bytes.  The largest isoch packet is
  98. probably about 2000 bytes.  Packets larger than this will cause cryptic error
  99. messages.
  100.  
  101. ** OUTPUT **
  102.  
  103. In general, hex values are displayed with zero-padding, while decimal values
  104. are not (except the running totals).  Usually it should be obvious which is
  105. which, but FireBug could possibly be more consistent.  Cycle timer and timestamp
  106. values are of the form seconds:cycles:offset, where seconds counts from 0 to
  107. 127, cycles counts from 0 to 7999, and offset counts from 0 to (I think) 3071.
  108. The Cycle timer in the upper left reads "CycleStart" and shows the most recently
  109. received cycle start packet, if there is a cycle master.  It reads "CycleTimer"
  110. when the local clock is being used because no cycle starts are arriving.  [This
  111. does not affect timestamping, which is always done with the local clock.]
  112. The NodeID, Root, and CPS values show FireBug's current Node ID on the FireWire
  113. bus, whether or not FireBug is root, and the value of the CPS (Cable Power Status)
  114. bit in the PHY.  [Root does not (usually) indicate the node ID of the root node.]
  115.  
  116. Running totals (tCodes, acks, etc.) show both the cumulative total, and the
  117. total for the last second.  One second is defined in one of two ways.  If we
  118. are receiving cycle start packets, then one second is measured by when the
  119. second field in those snooped packets increments.  In this case, the cycSt
  120. counter should show exactly 8000 cycle start packets each second, and the
  121. isoch counter should be accurate (8000/second from the DV camera, 7200/second
  122. from the CCM camera, etc.)  If we are not snooping cycle starts, then the local
  123. cycle timer will be used.  However, its value is checked by software, not using
  124. the recorded timestamps, so one second may not be perfectly accurate.  But,
  125. if there are no cycle start packets, perfect accuracy in measuring seconds may
  126. not matter.  [I'll probably fix this to use the sampled timestamps as the local
  127. time base, which should improve the accuracy.  For best results for now, make
  128. sure there is a cycle master if accuracy matters in the per-second fields.]
  129.  
  130. If a node sends more than one Self-ID packet (because it has 4 or more ports),
  131. each will be shown, but only the first one will be decoded.
  132.  
  133. Packets with all tCodes can be formatted for display.  Payload of block packets
  134. (write block, read block respones, lock request/response, and isoch) can be
  135. displayed in Hex/ASCII dump.
  136.  
  137. Bus reset timestamps are really the timestamp of the next received packet,
  138. which ought to be a self ID.  [There is no way to measure the gap between the
  139. two yet.]  Exception:  If no packet is received immediately, the timestamp is
  140. instead determined by software, and is approximate.
  141.  
  142. All output except the command history can be saved to a file with the "log"
  143. command.
  144.  
  145. ** COMMANDS **
  146.  
  147. If a PCI-Lynx card is detected, FireBug will automatically start snooping, with
  148. a default set of generally useful filters activated.  The commands documented
  149. below may be useful if you want to change the filtering parameters, or use other
  150. features of FireBug.  To exit FireBug, press command-Q or hold down the mouse
  151. button.  All commands are entered with the keyboard, similar to MacsBug, though
  152. some commands have command-key equivalents.  FireBug has no menu bar.  Holding
  153. down the mouse button should cause FireBug to quit even if it is too busy looking
  154. at packets to look at the keyboard.
  155.  
  156. Some commands have command-key equivalents.  These commands can be used at any
  157. time, even if another command is being entered with the keyboard.  Processing
  158. of keystrokes is completely asynchronous, and a typed command is only parsed when
  159. enter or return is pressed.  In particular, you can type in a command (such as
  160. tcode off) and then wait to press return until some critical moment, and, you
  161. can use command-key commands (such as busreset (command-R)) while you are waiting
  162. to press return.
  163.  
  164. To repeat the last typed command, press command-return or command-enter.
  165.  
  166. The remainder of this document lists the various commands supported by FireBug.
  167.  
  168. ** FILTERS **
  169.  
  170. FireBug snoops all packets (even cycle-starts) from the FireWire bus.  All of
  171. these packets are counted in the running totals of tCodes, speeds, etc.  Only
  172. some of these packets will be shown in formatted output.  When selecting filters,
  173. best results will be obtained by choosing filters that yield only a few hundred
  174. packets per second, or less.
  175.  
  176. FireBug's filters are mostly subtractive.  This means that a packet must
  177. satisfy every filter in order to be shown in the formatted output.  The general
  178. assumption is that you are looking for one particular packet of interest, not
  179. several kinds of packets.  For example, if you filter for tCode 1 (Write block)
  180. and ACK 1 (complete), you will see only block write packets for which the target
  181. node responded with an ack_complete.  You will not see any other packets that
  182. caused ack_complete, and you will not see any other block write packets.
  183.  
  184. There is a master filter that controls all non-error output.  To toggle this
  185. filter, press command-F.  To turn off the master filter whether it is already
  186. off or not, press Escape.  To turn on the master filter if you don't know its
  187. current state, press Escape, then command-F.  Both Escape and command-F can be
  188. used if you have already typed in part of another command, and they will not
  189. interfere with what you have typed.
  190.  
  191. The filters currently implemented are: tCode, ack, short.
  192.  
  193. The tCode and ack filters operate as follows:  Any or all of the filter values
  194. may be selected.  For example, the tCode filter can be set to match tCodes 4, 6,
  195. 9, and b (quadlet read, quadlet response, lock request, and lock response).  The
  196. filter can also be set to match all tCodes, in which case the filter has no
  197. effect, or to match no tCodes, in which case the filter removes all packets
  198. except PHY packets (which do not have any tCode).  The following commands are
  199. used to set the tCode filter:
  200.  
  201. > tcode on                // match all tCodes (disables filter)
  202. > tcode off               // match no tCodes (no async or isoch packets)
  203. > tcode 4 6 9 b           // show only quadlet read/response & lock req/resp
  204. > tcode 469b              // (same as above)
  205. > tcode on 469 b          // add tCodes 4, 6, 9, and b to the current filter
  206. > tcode off 4 6-b         // remove tCodes 4, 6, 7, 8, 9, a, and b
  207. > tcode                   // show current filter settings
  208.  
  209. The "short" filter will show block packets only if they are shorter than their
  210. header says they should be:
  211.  
  212. > short on
  213.  
  214. The window command can be used to display a fixed number of packets before and
  215. after any packet that passes the filter.  For example, you could filter on ack
  216. 4 (busyX) and d (data error) and set the window to show the previous and next 2
  217. packets.  The previous packets might have interesting timestamps (say, unusually
  218. close together), and the following packets might show retries.  This command has
  219. three forms:
  220.  
  221. [Note, command is xwindow until I clean it up]
  222.  
  223. > xwindow 3 10                   // show 3 packets before and 10 after any filtered packet
  224. > xwindow 5                // show 5 packets before and after any filtered packet
  225. > xwindow                  // show current window setting
  226.  
  227. The window command acts as an override, showing some packets that might not have
  228. been seen.  The extra packets are still subject to filtering, meaning that if they
  229. also pass a filter, they will cause yet more window packets to be shown.  However,
  230. packets that fall in multiple windows are not shown multiple times.
  231.  
  232. The window command does not quite correctly handle previous packets yet, in three
  233. ways.  First, if the pre-packet window includes bus resets, they will be shown
  234. out of order (they will preceed the windowed packets).  The timestamps may be
  235. helpful in finding the true order of events.  Also, pre-packet window packets
  236. will display incorrect ack codes and true packet lengths, and may have incorrect
  237. length payload dumps.  [Payload lengths from headers should be correct.  Try a
  238. pre-packet window on isochronous packets to see the problem clearly.]  Finally,
  239. pre-window packets will include cycle starts, because the last N non-cycle-start
  240. packets could have been so long ago that the buffer has already been recycled.
  241. [However, I hope to improve this by using a secondary window buffer].
  242.  
  243. To disable windowing, use the command "window 0".  The maximum pre- and post-packet
  244. window sizes are 99 and 500.  Note that windowing shows all packets, even cycle
  245. starts, during the pre-window period, but only all packets except cycle starts
  246. during the post-window period.
  247.  
  248. The cyclestart command is related to the window command, and controls how many
  249. cycle start packets are shown after a filtered packet.  This is different from
  250. the window command, which selects how many non-cycle-start packets are shown
  251. after a filtered packet.  The cyclestart command also has two forms:
  252.  
  253. > cyclestart 2            // show 2 cycle starts after any filtered packet
  254. > cyclestart              // report current setting
  255.  
  256. There is a special filter for looking for missing isochronous packets:
  257.  
  258. [Note, command is xisogap until I clean it up]
  259.  
  260. > xisogap 62
  261.  
  262. This filter (technically) matches a cycle start packet that follows a missing
  263. isochronous packet.  The filter works as follows:  When a cycle start packet
  264. is received, the filter is "armed".  When isochronous channel 62 is received,
  265. the filter is "disarmed".  If another cycle start packet arrives when the filter
  266. is "armed", this triggers the filter, because two cycle starts arrived without
  267. a channel 62 packet between them.  The filter will not operate again until a
  268. channel 62 packet arrives (otherwise, it would fire forever once channel 62
  269. shut down).  You probably want to use "isogap" together with the "window" option
  270. in order to see the real isochronous packets before and after the missing packet,
  271. so that you can examine the payloads or timestamps or whatever.
  272.  
  273. You can disable this filter by setting it to an illegal channel number (eg 64).
  274. When used with an isochronous source such as the CCM camera, that only transmits
  275. on 7200 out of every 8000 cycles, the filter will be triggered fairly often.
  276. Only one isochronous channel can be monitored for gaps with this filter.
  277.  
  278. There is a special filter for displaying a burst of isochronous packets:
  279.  
  280. > isosnap 20
  281.  
  282. This filter causes the next 20 (or any number specified) isochronous packets
  283. to be displayed, regardless of the other filters.  This filter turns itself
  284. off after the "snapshot" is complete, or it can be cleared by setting it to zero.
  285.  
  286. ** OPTIONS **
  287.  
  288. FireBug attempts to record a timestamp for each snooped packet or bus reset event.
  289. Because of the nature of Lynx and the PCLs used to control it, the recorded
  290. timestamps indicate a time shortly after a packet was completely transferred into
  291. Mac memory.  This time differs from the actual packet arrival time for two main
  292. reasons.  First, Lynx contains a FIFO that buffers received packets in order to
  293. compensate for PCI access latencies.  After a packet finishes arriving from the
  294. bus, the packet will not finish arriving in Mac memory until the FIFO has drained.
  295. This delays the capture of the timestamp.  The second reason for delay is the
  296. operational speed of the PCL engine in Lynx.  Once the packet has been placed in
  297. memory, Lynx (like a CPU) must fetch its next instruction.  The next instruction
  298. after each packet reception is to sample the local cycle timer and record the
  299. value in memory.  This operation requires several PCI accesses, so it consumes
  300. more time.  [Note that once the cycle timer value has been sampled, the additional
  301. delay of the accesses required to store that sample in memory will not affect the
  302. timestamp value.  In specific Lynx terms, the PCL operations are RCV to snoop a
  303. packet, followed by LOAD to copy the cycle timer to the Lynx temporary register,
  304. and finally STORE_QUAD to record the cycle timer in host memory along with the
  305. snooped packet.]
  306.  
  307. Timestamps are based on the local cycle timer, which is not synchronized to the
  308. received cycle start packets.  There could be some drift.  [This may change.]
  309.  
  310. Timestamp display is optional, and can be controlled with these two commands:
  311.  
  312. > timestamp on
  313. > timestamp off
  314.  
  315. Presently, disabling timestamps does not cause a change to optimize the Lynx PCLs.
  316. The timestamps are still recorded by the DMA, they just aren't shown to you.  This
  317. leads to a small performance improvement, because less information is being drawn on
  318. the screen, but the DMA performance does not change.
  319.  
  320. FireBug can display a hex dump of packet payloads.  Packets with tCodes of 1
  321. (block write), 7 (read block response), 9 (lock request), A (isochronous), and
  322. B (lock response) have variable-length payloads.  To specify the number of quadlets
  323. of payload to be dumped, use the data command:
  324.  
  325. > data 8
  326.  
  327. The above command causes (up to) 8 quadlets of payload to be displayed for all of
  328. the above packets (when they pass all active filters).  The actual number of quadlets
  329. shown will depend on the true length of each received packet.  To see the entire
  330. contents of such packets, use an impossibly large quadlet count, such as 1025.
  331. To disable payload dumping, specify 0 quadlets.  The default value is 0.
  332.  
  333. Note that displaying payload contents takes a while, and will reduce the maximum
  334. rate at which packets can be displayed.  Select the lowest number of quadlets
  335. possible to get best performance.
  336.  
  337. Payloads that are not an exacty number of quadlets are zero-padded in 1394.  The
  338. snooped packets should show this zero padding.
  339.  
  340. ** HISTORY **
  341.  
  342. FireBug presently stores 20479 lines of snooped packet history.  You can scroll
  343. back through this history using the up/down arrow keys, the page up/down keys,
  344. and the home/end keys.  Any new activity will cause the history to snap back to
  345. the bottom.  The key repeat rate for a key that is held down can be set with the
  346. Keyboard control panel.  Holding an arrow key down for a while will also cause
  347. FireBug to scroll faster (up to triple-speed).
  348.  
  349. The history consists of 20479 lines of text, not (usually) the last 20479
  350. packets on the bus.  There is no way to apply or change filters after the fact.
  351.  
  352. You can save part or all of the history to a file, together with the latest
  353. cumulative statistics.  Use the "log" command, with an optional count of the
  354. number of lines to write out.  This command writes the last 1000 lines of
  355. history, plus statistics, to a file:
  356.  
  357. > log 1000
  358.  
  359. With no argument, "log" writes the entire history buffer.
  360.  
  361. ** OTHER **
  362.  
  363. > map pciName <count>
  364.  
  365. The map command tells FireBug to try to use a particular Lynx chip by mapping its
  366. registers.  Because FireBug searches for Lynx using TI's vendor ID and device ID,
  367. most users will not need this command.
  368.  
  369. If you have multiple Lynx interfaces with the same PCI name, you can add a count
  370. argument to map to indicate which one you want.  (This may not work.)
  371.  
  372. Warning:  The map command looks up the name you give it in the Name Registry, then
  373. attempts to map the first matching entity into memory.  FireBug will then try to
  374. activate snooping.  If the thing you map is not a Lynx chip, FireBug can wreak havoc
  375. on your system by writing meaningless data to hardware.  Be careful!  Don't even
  376. think about using "map" on another kind of 1394 interface, such as OpenHCI or Pele.
  377. This won't work at all, and may screw up your Mac.
  378.  
  379. Map with no arguments will stop FireBug.  You can use the map command even if
  380. FireBug is already snooping, to switch to another chip.
  381.  
  382. > busreset (Command-R)
  383.  
  384. The busreset command will cause FireBug to initiate a reset of the FireWire bus by
  385. writing the IBR bit of PHY register 1.  In the rare event that FireBug detects a
  386. bus reset or other interrupt while it is attempting to trigger a reset, it will
  387. abort its attempt.
  388.  
  389. You can hold down Command-R to fire off large quantities of bus resets.  This can be
  390. a useful way to test the robustness of your software, without wearing out connectors.
  391.  
  392. > sync (Command-S)
  393.  
  394. FireBug will suspend snooping for a brief period (typically less than a millisecond)
  395. so that the Lynx cycle timer can be updated with an incoming cycle start packet.
  396. This allows timestamps to reflect the "real time" on the bus.  It is interesting to
  397. snoop cycle start packets after performing a sync; one can watch the Lynx clock drift
  398. out of sync with the cycle master.  Examining the timestamps of snooped cycle starts
  399. also yields some insights as to the accuracy of the timestamp mechanism.
  400.  
  401. Using the sync command will cause some packets to be missed (at least one cycle start,
  402. and any other packets arriving during the sync time).  Examining the per-second counts
  403. may give some indication of the impact of the sync.
  404.  
  405. After the local cycle timer has been updated, FireBug will display one cycle start
  406. packet in the packet output, regardless of filter settings.  At present, this is a
  407. cycle start taken somewhat randomly.  [I hope to change this so that the very first
  408. cycle start after the sync will be shown instead.]
  409.  
  410. Because the sync command must disable the snoop function, Lynx sometimes picks up
  411. a garbage packet as a result.  I think this is a hardware "feature".  If using sync
  412. during isoch or heavy async traffic, watch for unusual/illegal packets.
  413.  
  414. > zero (Command-Z)
  415.  
  416. All cumulative-total counts will be zeroed.  Filters and other operations are not
  417. affected.
  418.  
  419. > clear (Command-K)
  420.  
  421. The scrolling window of snooped text will be cleared.
  422.  
  423. > bread address length
  424.  
  425. This command sends a block-read request packet on the bus.  The outbound packet
  426. will not be shown in the snoop history, but the response (if any) will be shown - 
  427. if it passes the active filters.  You can use this command to read the CSR of a
  428. remote node, or any other address.  Note that if an error is reported, the ack
  429. that is reported may not be meaningful.  Typical usage of the bread command is:
  430.  
  431. > bread ffc0fffff000040c 8
  432.  
  433. This sends a block read request to node 0 for CSR ROM address 40C of length 8.
  434. The returned data (if the target supports block reads) will be the 8-byte
  435. unique ID of node 0.  You can specify length 4, and FireBug will still send a
  436. block read (not a quadlet read).  Technically, it should probably use a quadlet
  437. read instead.  However, FSL, the Sony DV camera, and the Sony CCM camera are all
  438. willing to respond to block reads of length 4.  Be sure to enable the correct
  439. filters so that you can see the response.  ("tcode on 67", "ack all" and "data 4"
  440. (or more)).
  441.  
  442. > qread address
  443.  
  444. This command works just like bread, except that it sends tCode 4 (quadlet read
  445. request) and you don't specify a length.  Some devices won't respond to block
  446. reads in their CSR, even of length 4, but will respond to quadlet reads.
  447. Example:
  448.  
  449. > qread ffc1fffff000040c
  450.  
  451. Note that FireBug does not acknowledge the response to a bread or qread
  452. command, and this can confuse the other node.
  453.  
  454. FireBug can read and write PHY registers using these commands:
  455.  
  456. > phyread 0
  457.  
  458. > phywrite 1 40
  459.  
  460. Register numbers are decimal arguments (0-15), the write data is given in hex.
  461. The above example reads register 0, then forces a bus reset.  Use with caution.
  462.  
  463. FireBug can send PHY configuration packets using these self-explanatory commands
  464. that take one hex argument each:
  465.  
  466. > phyconfig 00ff0000                   // Raw packet (force root 0, gap count 3f)
  467.  
  468. > gap 3f                               // Set gap count 0x3f only
  469.  
  470. > root 4                               // Set force_root 0x4 only
  471.  
  472. > linkon 1c                            // Send link-on to node 0x1c
  473.  
  474. FireBug can read and manipulate the Lynx GPIO pins using these commands:
  475.  
  476. > gpio                                 // Show current values only
  477. > gpio 0 on                            // Set GPIO 0 to output a one
  478. > gpio 3 off                           // Set GPIO 3 to output a zero
  479. > gpio 2 z                             // Put GPIO 2 in tristate
  480.  
  481. On the Apple FireWire DV card, "gpio 0 on" sets the contender bit.  FireBug
  482. places all four GPIOs in tristate when it starts up.  Only one GPIO can be
  483. manipulated per command.  The state shown does not indicate whether FireBug
  484. is driving the state, or sampling it (tri-state) [You are supposed to remember
  485. how you set them].  DANGER:  Make sure you know what the GPIOs do on your
  486. particular hardware before you use this command.
  487.  
  488. These commands can turn off (or on) the hardware sampling of one timestamp
  489. and one interrupt set per packet:
  490.  
  491. > sampletime off
  492. > sampleints off
  493.  
  494. When timestamp sampling is off, timestamps are not shown.  When interrupt
  495. sampling is off, interrupts (notably, bus reset) are not shown.  Bus resets
  496. can be inferred from the presence of self-ID packets.  Turning off both
  497. options will eliminate a lot of DMA/PCI overhead.
  498.  
  499. The snoop command can turn off snooping.  When snooping is off, Lynx will
  500. receive only packets sent to it, rather than receiving all packets.  Lynx
  501. will still receive all isoch packets.  Asynch packets sent to Lynx will be
  502. acknowledged with ack_pending or an error ack.  FireBug will not see cycle
  503. start packets when snooping is off, but the cycle timer will be updated if
  504. cycle start packets arrive.
  505.  
  506. > snoop off
  507.  
  508. Two utility commands are provided that have nothing to do with the card (if any)
  509. FireBug is using:
  510.  
  511. The first command performs a CRC on seven bytes, as used in the serial EEPROM on
  512. Lynx.  Exactly seven bytes of hex data must be entered as shown here, with leading
  513. zeroes, and with one space between.  For example, these values from the TSBKPCI
  514. card give the answer 0x70:
  515.  
  516. > lynxCRC 04 03 02 4c 10 03 80
  517.  
  518. The other utility command computes 1394-style Bus Info Block checksums.  Exactly
  519. four quadlets of hex data, each eight characters long, must be entered.  One
  520. space is used between each value.  (Type carefully!)  The CRC is computed, and
  521. the resulting five-quadlet Bus Info Block is displayed.  For example:
  522.  
  523. > romCRC 31333934 f0647000 08002851 000009de
  524.  
  525. ** DEFAULTS **
  526.  
  527. FireBug's default configuration is essentially what would result from these commands:
  528.  
  529. > zero
  530. > clear
  531. > tcode 0-7 9 b-f
  532. > ack on
  533. > data 0
  534. > window 0
  535. > cyclestart 0
  536. > timestamp on
  537. > snoop on
  538. > sampleints on
  539. > sampletime on
  540. > short off
  541.  
  542. ====================================================================================
  543. Version history
  544.  
  545. 97.02.03
  546. * First internal distribution.
  547.  
  548. 97.02.10
  549. * Fixed payload size displayed for block write packet (forgot to >> 16).
  550. * Added "map" command to allow use with 3rd party Lynx cards.
  551. * The check for missed interrupts was made tighter.  Warnings should be more rare now.
  552.  
  553. 97.02.12
  554. * Added "data" command to dump payloads.
  555.  
  556. 97.02.25  1.0d1
  557. * Fixed payload dump for payloads with zero-padding.
  558. * Fixed tCode 7 (block response) payload display.
  559. * Added "bread" command to send block read requests.
  560.  
  561. 1.0d2
  562. * Added tCodes 1, 5, and 7 to default settings.
  563. * Lock request/response packets, if shown, always dump at least 4 quads of payload.
  564. * Now look for both pci104c,8003 and pci403,605 automatically at startup.
  565. * Added "qread" command to send quadlet read requests.
  566. * Added "clear" command to clear scrolling snoop history.
  567. * Added master filter (Command-F and Escape key).
  568. * Added "window" and "cyclestart" commands, though they still need work.
  569. * Now check keystrokes more often when swamped with packets.
  570. * Added "isogap" command to look for missing isochronous packets.
  571.  
  572. 97.11.03  1.0d3e1
  573. * Not sure of the distribution for 1.0d2, renumbered to be safe.
  574. * Added "isosnap" command.
  575. * Renamed "window" to "xwindow" and "isogap" to "xisogap" until they're cleaner.
  576.  
  577. 98.02.08  1.0d3e2
  578. * Added lynxCRC and ROMCRC commands to compute EEPROM CRC values.
  579.  
  580. 98.03.12        1.0d4e1 (Clinton Bauder)
  581. * Look for pci106b,1a Lynx cards.
  582. * Support Self-ID packets for PHYs with >3 ports.
  583. * Build with CodeWarrior 11.
  584.  
  585. 98.03.29  1.0d4e2
  586. * Added auto-detect of any Lynx card.
  587. * Added save-to-file ("log").
  588. * Added last command repeat (press command-enter or command-return).
  589. * Sources now include both CW9 and CW11 project files.
  590. * Added resource file with version string.
  591.  
  592. 98.05?  1.0d4e3
  593. * Clinton added some 1394a PHY support.
  594.  
  595. 98.05?  1.0d4e4
  596. * Unknown changes (none?)
  597.  
  598. 98.06.22  1.0d5e1
  599. * Added support for VM and ROM-in-RAM / New World.
  600. * Added phyread and phywrite commands.
  601. * Added Command-K shortcut for "clear" command.
  602.  
  603. 98.07.07  1.0d5e2
  604. * Fixed bug in Bus Reset to make more reliable (fewer "interrupted" errors).
  605.  
  606. 98.07.25  1.0d5
  607. * Version for distribution with FireWire 1.1 SDK.
  608. * Fixed negative actual packet sizes in block read/write packets
  609. * Removed write to PHY register 0xD during setup (this fixed an early
  610.   prototype PHY but makes current versions fail).  Use "phywrite" instead.
  611.  
  612. 98.08.01  1.0d6
  613. * Real version for distribution with FireWire 1.1 SDK.
  614. * Show speed code on all snooped packets (except PHY packets): s100, s200, or s400.
  615. * Detect missing self-ID packets ("m" bit set, followed by bit 23 clear).
  616. * Added phyconfig, gap, root, and linkon commands to send PHY packets.
  617. * Added gpio command to read and control Lynx GPIO pins.
  618.  
  619. 99.??.??  1.0d7
  620. * No longer set Posted Writes or enable Slave Bursts - Lynx rev A says not to.
  621. * Added short command to show only short block packets.
  622. * Count short block packets [and any non-4n packet!] as DMA errors.
  623. * New index argument for map command (e.g. "map pci104c,8003 2" for second card).
  624. * No longer clear PCI Write Invalidate Enable bit on startup.
  625. * New sampletime and sampleints commands.
  626. * Can map another Lynx chip while running.
  627. * Added snoop command to disable snoop.
  628. * Report more information about chip we use.
  629. * Added SBP-2 decode feature.  "sbp off" to disable it.  Accurate until a bus reset.
  630. * Now show any non-zero rCode on snooped packets.
  631. * Can put a comment in the log text by preceeding it with *.  Enter only * for a line of *s.
  632. * Show tLabel for write req/resp.  Show rCode in write response.
  633.  
  634. ====================================================================================
  635. FireBug software and documentation (mostly) by Eric Anderson, ewa@apple.com
  636. Copyright 1997-1999, Apple Computer, Inc.
  637.